FSAllocateFork

FSAllocateFork
Header:	Files.h		Carbon status:	Supported

Attempts to reserve space on a volume for use by an open fork.

OSErr FSAllocateFork (
    SInt16 forkRefNum, 
    FSAllocationFlags flags, 
    UInt16 positionMode, 
    SInt64 positionOffset, 
    UInt64 requestCount, 
    UInt64 *actualCount
);

forkRefNum: The reference number of the fork.
flags: Controls how new space is allocated. If the kAllocContiguousMask is set, then then any newly allocated space must be in one contiguous extent (preferably contiguous with any space already allocated). If kAllocAllOrNothingMask is set, then the entire requestCount bytes must be allocated for the call to succeed; if not set, as many bytes as possible will be allocated (without error). If kFSAllocNoRoundUpMask is set, then no additional space is allocated (such as rounding up to a multiple of a clump size); if clear, the volume format may allocate more space than requested as an attempt to reduce fragmentation. See “Allocation Flags”.
positionMode: The base location for the start of allocation.
positionOffset: The offset of the start of allocation.
requestCount: The number of bytes to allocate.
actualCount: On return, a pointer to the number of bytes actually allocated to the file. The actualCount may be smaller than requestCount if some of the space was already allocated. The actualCount output is optional; if you don’t want it, set actualCount to NULL.The value returned in actualCount does not reflect any additional bytes that may have been allocated because space is allocated in terms of fixed units such as allocation blocks, or the use of a clump size to reduce fragmentation.

function result: A result code.

DISCUSSION

This call will attempt to allocate requestCount bytes of physical storage starting at the offset specified by positionMode and positionOffset. For volume formats that support preallocated space, you can later write to this range of bytes (including extending the size of the fork) without requiring an implicit allocation.

Any extra space allocated but not used will be deallocated when the fork is closed, using FSCloseFork, or flushed, using FSFlushFork.

AVAILABILITY

Supported in Carbon. Available in Mac OS 9, and later when Carbon 1.0.2 or later is present.